Topology APIs

GET /api/v2/topology/detail/default

Description

Get the list of links between devices and device details to build and study the device topology map.

Header Parameters

Name	Description	Type	Required	Default
Authorization	Bearer API token/key. The format is Bearer <API_key>	String	Yes
orgId	The ID of the organization. The format is OrgId:OrgName	String	Yes
siteId	The ID of the site. The format is SiteId:SiteName	String	Yes

Query Parameters

Name	Description	Type	Required	Default
days	The number of days to go back to	Integer	No	1
hiddenDevices	Flag for showing/hiding hidden devices. If enabled, the result will include the hidden devices	Boolean	No	false
view	Topology view (svg/canvas)	String	No	svg
enrich		Boolean	No
force		Boolean	No
persist		Boolean	No

CURL Example

The below code snippet shows an example of the API call, where <NCE-IP>, <ORG-ID>, <SITE-ID> & <API-TOKEN> are variables.

curl --location 'https://<NCE-IP>/api/v2/topology/detail/default?days=14&view=svg' \
--header 'orgId: <ORG-ID>' \
--header 'siteId: <SITE-ID>' \
--header 'Authorization: Bearer <API-TOKEN>'

Response

Upon a successful request, the API returns Status code 200 with the following body:

Name	Description	Type
links	List of links between devices	Array of objects
- linkId	Link ID	String
- devAId	Device A ID	String
- devBId	Device B ID	String
- devAName	Device A hostname	String
- devBName	Device B hostname	String
- devAIfxName	Device A interface name	String
- devBIfxName	Device B interface name	String
- linkType	Link types list	Array of strings
- linkOperState	Link operational state	String
- vlanSet	VLans list	Array of strings
- linkRank	Link dispay rank	Integer
- devAIfxState	Device A interface state	String
- devBIfxState	Device B interface state	String
- operStateA	Device A operational state	String
- operStateB	Device B operational state	String
- vnetId		String
- noOfLinks	Links number	Integer
devices	List of devices included in the topology	Array of objects
- orgId	Organization ID	String
- siteId	Site ID	String
- deviceId	Device ID	String
- hostName	Device hostname	String
- vmName	Device VM name	String
- vendor	Device vendor name	String
- model	Device model	String
- platform	Device platform name	String
- platformType	Device platform type	String
- version	Device platform version	String
- serialNumber	Device serial number	String
- devType	Device type	String
- devSubType	Device subtype	String
- ipAddress	List of IPv4 addresses associated with the device	Array of strings
- ipv6Address	List of IPv6 addresses associated with the device	Array of strings
- discoveredIpSet	List of IPv4 addresses used in device discovery	Array of strings
- fqdn	Device fully qualified domain name (FQDN)	String
- fqdnList	Device fully qualified domain names list	Array of strings
- domainName	Device domain name	String
- isVirtual	Boolean yes/no if the device is virtual	String
- reachableList	List of protocols able to connect with the device	Array of strings
- unreachableList	List of protocols able to connect with the device. Each element in the object is constructed by "protocol":"Failure_reason"	Object
- deviceStatus	Device status	String
- deviceSubStatus	Device sub status	String
- managers	List of device managers names and IPs	Object of string tuples
- parents	List of device parent IDs	Array of strings
- parentHostNames	List of device parents hostnames	Array of strings
- d3Parents	List of device 3D parents	Array of strings
- clusters	List of device cluster IDs	Array of strings
- gatewaySet	List of device gateway IDs	Array of strings
- services	List of services running on the device	Array
-- fsAppRole	Service role	String
-- fsService	Service name	String
- serviceStatus		String
- cloud	Boolean true/false if is a cloud device	Boolean
- vnetId		String
- source	The source of the discovery information	String
- discovered	Boolean true/false if the device is considered discovered. Devices discovered by more than ping protocol are considered discovered	Boolean
- lastCMDBUpdateTime	Last time the record was pushed to the CMDB. The format is timeyyyy-MM-ddThh:mm:ss.tttZ	String
- lastDiscovered	Last time when the device was discovered. The format is timeyyyy-MM-ddThh:mm:ss.tttZ	String
storageDevices	List of storage devices. The object structure is the same as device	Array of objects
coordinates	List of coordinates on the topology map for each device	Array of objects
- deviceId	Device ID	String
- x	Device X position on the topology map	String
- y	Device Y position on the topology map	String
disconnectedDevices	List of devices with no links. The object structure is the same as device	Array of objects
imanStatus	Not in use	Null
applicationAlertStatus	Not in use	Null
applicationEventStatus	Not in use	Null

POST /api/v2/topology/group

Description

Get the list of links between devices and device details for a particular device group.

Header Parameters

Name	Description	Type	Required	Default
Authorization	Bearer API token/key. The format is Bearer <API_key>	String	Yes
orgId	The ID of the organization. The format is OrgId:OrgName	String	Yes
siteId	The ID of the site. The format is SiteId:SiteName	String	Yes

Query Parameters

Name	Description	Type	Required	Default
hiddenDevices	Flag for showing/hiding hidden devices. If enabled, the result will include the hidden devices	Boolean	No	false
view	Topology view (svg/canvas)	String	No	svg
force		Boolean	No
persist		Boolean	No

Body Parameters

Name	Description	Type	Required	Default
filterListContainer	Filter with the group ID. The format is JSON. Example {"filterMap":{"deviceGroupId": ["<groupID>"]}}	Object	Yes

CURL Example

The below code snippet shows an example of the API call, where <NCE-IP>, <ORG-ID>, <SITE-ID>, <API-TOKEN> & <GROUP-ID> are variables.

curl --location 'https://<NCE-IP>/api/v2/topology/group?view=svg' \
--header 'orgId: <ORG-ID>' \
--header 'siteId: <SITE-ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-TOKEN>' \
--data '{
    "filterMap": 
    {
        "deviceGroupId": [
            "<GROUP-ID>"
        ]
    }
}'

Response

Upon a successful request, the API returns Status code 200. The response model is the same as the response for GET /api/v2/topology/detail/default

GET /api/v2/topology/undiscovered

Description

Get the list of undiscovered devices. Includes all links that have only one link end (A or B) and the other end is an unknown device that is not yet discovered.

Header Parameters

Name	Description	Type	Required	Default
Authorization	Bearer API token/key. The format is Bearer <API_key>	String	Yes
orgId	The ID of the organization. The format is OrgId:OrgName	String	Yes
siteId	The ID of the site. The format is SiteId:SiteName	String	Yes

Query Parameters

Name	Description	Type	Required	Default
view	Topology view (svg/canvas)	String	No	svg

CURL Example

The below code snippet shows an example of the API call, where <NCE-IP>, <ORG-ID>, <SITE-ID> & <API-TOKEN> are variables.

curl --location 'https://<NCE-IP>/api/v2/topology/undiscovered' \
--header 'orgId: <ORG-ID>' \
--header 'siteId: <SITE-ID>' \
--header 'Authorization: Bearer <API-TOKEN>'

Response

Upon a successful request, the API returns Status code 200. The response model is the same as the response for GET /api/v2/topology/detail/default

GET /api/v2/topology/link/memberLink

Description

Get details for a particular link by link ID.

Header Parameters

Name	Description	Type	Required	Default
Authorization	Bearer API token/key. The format is Bearer <API_key>	String	Yes
orgId	The ID of the organization. The format is OrgId:OrgName	String	Yes
siteId	The ID of the site. The format is SiteId:SiteName	String	Yes

Query Parameters

Name	Description	Type	Required	Default
linkId	Llink ID	String	Yes
page	Page number, starting from 1	String	No	1
size	Number of devices per page. Minimum size is 1	String	No	10
sort	Sorting criteria in the format: property, (asc, desc). Multiple sort criteria are supported	String	No

CURL Example

The below code snippet shows an example of the API call, where <NCE-IP>, <ORG-ID>, <SITE-ID>, <API-TOKEN> & <LINK-ID> are variables.

curl --location 'https://<NCE-IP>/api/v2/topology/link/memberLink?linkId=<LINK-ID>&page=1&size=10' \
--header 'orgId: <ORG-ID>' \
--header 'siteId: <SITE-ID>' \
--header 'Authorization: Bearer <API-TOKEN>'

Response

Upon a successful request, the API returns Status code 200 with the following body:

Name	Description	Type
linkId	Link ID	String
devAId	Device A ID	String
devAIfxName	Device A interface name	String
devAIfxState	Device A interface state	String
devAName	Device A hostname	String
devBId	Device B ID	String
devBIfxName	Device B interface name	String
devBIfxState	Device B interface state	String
devBName	Device B hostname	String
linkOperState	Link operational state	String
linkRank	Link dispay rank	Integer
linkType	Link types list	Array of strings
noOfLinks	Links number	Integer
operStateA	Device A operational state	String
operStateB	Device B operational state	String
vlanSet	VLans list	Array of strings
vnetId		String